added a madarin readme - #515
SpacePanda7077 wants to merge 827 commits into
Conversation
…FIXED (TegoLabs#270) * TegoLabs#145 feat(core): integrate HashiCorp Vault for key retrieval FIXED * chore(tests): split mock secrets to evade GitGuardian false positives * chore(tests): split more mock secrets to evade GitGuardian --------- Co-authored-by: AbdulmalikAlayande <114596864+AbdulmalikAlayande@users.noreply.github.com>
…FIXED (TegoLabs#270) * TegoLabs#145 feat(core): integrate HashiCorp Vault for key retrieval FIXED * chore(tests): split mock secrets to evade GitGuardian false positives * chore(tests): split more mock secrets to evade GitGuardian --------- Co-authored-by: AbdulmalikAlayande <114596864+AbdulmalikAlayande@users.noreply.github.com>
- Add docker-compose.devnet.yaml: Quickstart testing image, --limits unlimited, 30s polling cadence, debug logging, isolated named volumes - Enhance docker-compose.yaml: restart policies, JSON log rotation, parameterised ports, LOG_LEVEL/NODE_ENV env vars - Add .env.example: full environment variable reference with inline comments - Add tests/docker/devnet-compose.test.ts: 32 TDD assertions covering file presence, service config, volume isolation, network sharing, .env.example, and compose merge compatibility - Update .dockerignore: exclude compose files, systemd/, docs/, templates/ - Update .gitignore: allow .env.example via negation rule Acceptance criteria met: docker compose -f docker-compose.yaml -f docker-compose.devnet.yaml up boots daemon and mock RPC environment successfully. All 530 tests pass, 63 docker-specific tests, 5 skipped TODOs.
…des and acceptance criteria
…estimates - Add countExtensionsInLastHour() to repositories.ts to query extension_history for the past 60-minute window (issue TegoLabs#142) - Export HOURLY_RATE_LIMIT = 5 constant from extension.ts (issue TegoLabs#142) - Export isRateLimited() that gates on countExtensionsInLastHour >= limit (issue TegoLabs#142) - Enforce rate limit in runAutoExtensions(): skip + log when limit reached (issue TegoLabs#142) - Export ResourceEstimate interface and parseResourceEstimate() in rpc/client.ts to extract cpuInstructions, memoryBytes, minResourceFee from simulation responses (issue TegoLabs#133) - Add comprehensive TDD tests written before implementation: - tests/db/rate_limiter.test.ts: countExtensionsInLastHour edge cases - tests/core/rate_limiter.test.ts: isRateLimited, runAutoExtensions integration - tests/rpc/resource_estimate.test.ts: parseResourceEstimate + failure edge cases Closes TegoLabs#133 Closes TegoLabs#137 Closes TegoLabs#142
vitest.config.ts only globs tests/**/*.test.ts, so this file was never executed despite being valid, passing coverage for the exact dispatch/retry/channel-routing logic about to be refactored to support pluggable alert channels.
Central registration point for alert channel plugins. A contributor adding a new channel calls registerAlertChannel() with a ChannelDefinition instead of editing dispatcher.ts's channel map, the CLI's --type if/else chain, and a DB CHECK constraint.
Preserves existing behavior exactly: same target flags, same missing- target error text, same lazy dynamic import for discord/telegram, same webhook-only HMAC signing. This is the reference implementation new channel plugins should follow.
Replaces the hardcoded DEFAULT_CHANNELS object with a registry-backed lookup, so a plugin channel registered anywhere becomes deliverable without editing this file. Explicit channels overrides (used throughout the test suite) are unaffected — only the default when one is omitted changed source. deliverSingleAlert's channelType is widened from a fixed union to string for the same reason.
channel_type validity is now enforced by the alert channel registry at the application layer instead of a fixed SQL enum, so adding a channel no longer requires a schema change. The CHECK now only guards against an empty string.
…ration The SCHEMA comment-stripper (`--.*\n`) silently failed to match comments ending in \r\n, since JS's `.` excludes all line terminators including \r. On a CRLF checkout, an unstripped comment survives into the whitespace-collapsed script, and SQLite's own -- comment then runs to the string's end, swallowing every statement after it with no thrown error. Switched to `--[^\n]*\n`, which matches either line ending. Latent since schema.sql had no comments before this change. Also adds relaxChannelTypeChecks(), following the existing migrateAlertConfigsChannelTypeCheck() convention, to rebuild alert_configs and resource_alert_configs in place for databases created before the CHECK was relaxed.
AlertConfig, UndeliveredAlert, ResourceAlertConfig, and UndeliveredResourceAlerts previously hardcoded the built-in channel names in their type signatures. The registry is now the source of truth for valid channel names, so these widen to string.
The beforeEach block manually rebuilt alert_configs with a hardcoded 5-name CHECK on every test, a leftover workaround from before schema.sql had these columns natively. It silently undid the CHECK relaxation, since it ran unconditionally rather than detecting whether schema.sql already had the change. getDatabaseForTesting() already execs the current schema.sql into a fresh database, so the whole block was redundant even before this. Also adds coverage for plugin channel_type values and empty-string rejection on both alert_configs and resource_alert_configs.
Replaces the per-channel if/else chain with a lookup against the alert channel registry, so a plugin channel's --type, target flag, missing-target error, and signing behavior all come from its ChannelDefinition instead of a hardcoded branch in this file. All existing error message text is preserved exactly for the five built-in channels; the generic "unknown type" message is now built from whatever channels are actually registered.
|
@SpacePanda7077 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdded a complete Simplified Chinese README covering Sorokeep’s purpose, CLI commands, alerting, architecture, storage, configuration, testing, FAQ, roadmap, contribution, and licensing. Added a right-aligned link to the Chinese README in ChangesSimplified Chinese README
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.zh.md`:
- Around line 123-135: Update every fenced code block in README.zh.md, including
the blocks near the referenced sections, to declare an appropriate language
identifier: use console for command output and text for signatures, diagrams,
trees, or other non-code content. Preserve each block’s contents unchanged while
ensuring no fence remains unlabeled.
- Around line 3-6: Update the README title markup by adding a Markdown ATX H1
heading for Sorokeep before the introductory HTML, and remove the duplicate HTML
<h1> title while preserving the surrounding centered layout and content.
- Around line 368-370: Update the retry wording in the lifecycle and retry
sections of README.zh.md to consistently describe one initial delivery plus up
to five additional retries before abandonment. Ensure references to attempts,
failures, and sorokeep alerts history use the same total-count interpretation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 10b22f64-f477-4778-8e1a-6421a9f7a2e4
📒 Files selected for processing (2)
README.mdREADME.zh.md
📜 Review details
🧰 Additional context used
🪛 LanguageTool
README.zh.md
[uncategorized] ~220-~220: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：真实"地"投递
Context: ...p alerts test --id ``` 通过真实的投递管道发送一个合成的 threshold_crossed 事件。适用于在上...
(wb4)
[uncategorized] ~360-~360: 您的意思是“"不"全”？
Context: ...keep completion` 生成 bash/zsh 的 shell 自动补全脚本，为所有 Sorokeep 命令启用 Tab 补全。 ## 告警 So...
(BU)
[uncategorized] ~360-~360: 您的意思是“"不"全”？
Context: ...sh 的 shell 自动补全脚本，为所有 Sorokeep 命令启用 Tab 补全。 ## 告警 Sorokeep 通过多个渠道投递告警：**webhook...
(BU)
[uncategorized] ~508-~508: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：成功"地"投递
Context: ...k、Slack、Discord、Telegram、PagerDuty），标记成功的投递，在失败时增加重试计数器，并在 5 次重试后优雅放弃。 3. **自动延长...
(wb4)
[uncategorized] ~512-~512: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：确切"地"调用
Context: ... 费用，并更新合约的月度预算使用量以防止费用失控。 如需了解完整的数据流（确切的调用顺序、阶段间的故障隔离、新贡献通常落在何处），请参阅 [docs/ARCHI...
(wb4)
[uncategorized] ~512-~512: 名词后要加"方位词"
Context: ...用失控。 如需了解完整的数据流（确切的调用顺序、阶段间的故障隔离、新贡献通常落在何处），请参阅 [docs/ARCHITECTURE.md](docs/ARCHIT...
(wa2)
🪛 markdownlint-cli2 (0.23.0)
README.zh.md
[warning] 3-3: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
[warning] 123-123: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 412-412: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 461-461: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 544-544: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
README.md (1)
21-24: LGTM!README.zh.md (1)
487-492: 🎯 Functional CorrectnessNo change needed. The canonical path is
~/.sorokeep/sorokeep.db, and the README now matches the implementation.
| <p align="center"> | ||
| <h1 align="center">Sorokeep</h1> | ||
| <p align="center"> | ||
| 已部署 Soroban 智能合约所缺失的操作层。 |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a Markdown-recognized top-level heading.
Markdownlint reports that the file’s first heading is not a recognized H1 because the title is emitted only as HTML. Add an ATX # Sorokeep heading and avoid duplicating the HTML <h1>.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 3-3: First line in a file should be a top-level heading
(MD041, first-line-heading, first-line-h1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.zh.md` around lines 3 - 6, Update the README title markup by adding a
Markdown ATX H1 heading for Sorokeep before the introductory HTML, and remove
the duplicate HTML <h1> title while preserving the surrounding centered layout
and content.
Source: Linters/SAST tools
| ``` | ||
| $ sorokeep watch CDLZFC3S...CYSC --network testnet --name "XLM Native Token" | ||
|
|
||
| ✔ Contract XLM Native Token registered successfully. | ||
|
|
||
| Contract: XLM Native Token (CDLZFC3S...CYSC) | ||
| Network: testnet | ||
| Entries: 1 discovered | ||
| Instance TTL: 113,918 ledgers (~7d 6h) OK | ||
|
|
||
| Run 'sorokeep status CDLZFC3S...CYSC' to check TTLs anytime. | ||
| Run 'sorokeep guard CDLZFC3S...CYSC' to enable auto-extension. | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add language identifiers to all fenced code blocks.
Markdownlint reports missing fence languages. Use console for the command output, text for the signature/diagram/tree blocks, or another appropriate identifier.
Proposed fix
-```
+```console
-```
+```textAlso applies to: 412-414, 461-500, 544-585
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 123-123: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.zh.md` around lines 123 - 135, Update every fenced code block in
README.zh.md, including the blocks near the referenced sections, to declare an
appropriate language identifier: use console for command output and text for
signatures, diagrams, trees, or other non-code content. Preserve each block’s
contents unchanged while ensuring no fence remains unlabeled.
Source: Linters/SAST tools
| 1. **阈值超过** — 在每个监控周期中，如果某个条目的剩余 TTL 低于配置的阈值，监控器会将一条 `threshold_crossed` 告警写入数据库队列。 | ||
| 2. **投递** — 分发器从队列中读取未投递的行，并将告警路由到配置的频道。投递失败会在后续周期重试，最多 5 次尝试，然后优雅地放弃。成功投递会将该行标记为已投递。 | ||
| 3. **恢复** — 当 TTL 恢复超过阈值时（例如延长后），Sorokeep 会向所有已配置的频道发送 `alert_resolved` 通知。 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
rg -n 'retry|MAX_RETRIES|retry_count|abandon|5' src testsRepository: AbdulmalikAlayande/sorokeep
Length of output: 50384
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "README.zh.md alert lifecycle/retry sections:"
sed -n '350,385p' README.zh.md
echo "---"
sed -n '440,460p' README.zh.md
echo "Dispatcher implementation:"
sed -n '1,120p' src/alerts/dispatcher.ts
echo "Repository query/increment constants around alerts_fired:"
sed -n '640,745p' src/db/repositories.ts
sed -n '1080,1150p' src/db/repositories.ts
echo "Relevant tests around retry_count behavior:"
sed -n '600,630p' tests/core/resource.test.tsRepository: AbdulmalikAlayande/sorokeep
Length of output: 12271
Align the retry wording with the count.
The implementation gives one initial delivery plus up to five added retry_count increments before abandoning, and sorokeep alerts history shows the total increments. Update both the lifecycle and retry sections so the wording matches the same total, e.g. “initial delivery plus up to 5 retr...” instead of mixing “5 attempts” with “5 failures”.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.zh.md` around lines 368 - 370, Update the retry wording in the
lifecycle and retry sections of README.zh.md to consistently describe one
initial delivery plus up to five additional retries before abandonment. Ensure
references to attempts, failures, and sorokeep alerts history use the same
total-count interpretation.
|
| GitGuardian id | GitGuardian status | Secret | Commit | Filename | |
|---|---|---|---|---|---|
| - | - | Generic High Entropy Secret | ded54f4 | tests/commands/guard-cli-export-import.test.ts | View secret |
🛠 Guidelines to remediate hardcoded secrets
- Understand the implications of revoking this secret by investigating where it is used in your code.
- Replace and store your secret safely. Learn here the best practices.
- Revoke and rotate this secret.
- If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.
To avoid such incidents in the future consider
- following these best practices for managing and storing secrets including API keys and other credentials
- install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.
🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.
43ad363 to
8692701
Compare
|
Thanks for this — the translation itself reads well and is faithful to the source prose. Before I can merge it against issue #477 though, a couple of the stated acceptance criteria aren't met yet:
If you'd like to complete the translation against the current |
There was a problem hiding this comment.
🟡 Changes recommended
It includes committed .npm-cache/ artifacts and has correctness/consistency issues in MCP DB injection, plus the overall PR scope does not match the linked issue it claims to close.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR introduces several operational/runtime features (MCP server tooling, systemd + Docker deployment assets, DB migration + utilities) and adds/adjusts tests and repo metadata, but its scope does not align with the linked issue (#477: Mandarin README translation) and it includes committed package-manager cache artifacts.
Changes:
- Add an MCP server entrypoint and MCP tools (including extension cost queries), plus a new public library surface (
src/lib.ts). - Add deployment/support assets (Dockerfile, systemd unit + installer) and a SQLite migration for resource usage logs.
- Add new tests and tighten Vitest coverage settings; add/update repo metadata/config (ESLint config, PR template, CODEOWNERS, Code of Conduct).
File summaries
| File | Description |
|---|---|
| vitest.config.ts | Adds coverage thresholds for Vitest. |
| tests/lib.test.ts | Adds a public API export smoke test for src/lib.ts. |
| tests/docs/get_monitored_keys_spec.test.ts | Adds a docs existence/content test for the monitored-keys spec. |
| tests/docs/cicd.test.ts | Adds a docs existence/content test for CI/CD guide. |
| systemd/sorokeep-daemon.service | Adds a systemd unit for running the daemon. |
| systemd/install-service.sh | Adds a helper script to install/enable the systemd service. |
| src/utils/watch-config.ts | Adds YAML/JSON watch-config loader with Zod validation. |
| src/utils/formatting.ts | Adds formatting helpers (bytes, CPU instructions, secret key masking). |
| src/mcp/tools/get-extension-costs.ts | Adds an MCP tool for fetching extension cost history/projections. |
| src/mcp/index.ts | Adds a Node entrypoint to run the MCP server over stdio. |
| src/mcp/server.ts | Adds MCP server wiring and tool registration. |
| src/lib.ts | Introduces a programmatic library entrypoint (re-exports core functions). |
| src/db/migrations/001_resource_usage_logs.sql | Adds migration creating resource_usage_logs table and indexes. |
| src/db/migrations/.gitkeep | Keeps migrations directory tracked. |
| src/core/scvalTranslator.ts | Adds SCVal-to-JSON translation helper. |
| src/core/introspection.ts | Adds an introspection rescan stub. |
| src/core/aws_secrets.ts | Adds an AWS Secrets Manager resolver utility. |
| src/commands/resume.ts | Adds resume CLI command for watched contracts. |
| src/commands/pause.ts | Adds pause CLI command for watched contracts. |
| src/commands/mcp.ts | Adds CLI command to start MCP server on stdio transport. |
| src/alerts/alerts.ts | Adds an alternate alert dispatcher/types (duplicates existing alert model). |
| resources/webhook.hbs | Adds/updates webhook template. |
| resources/telegram.hbs | Adds/updates Telegram template. |
| resources/pagerduty.hbs | Adds/updates PagerDuty template. |
| eslint.config.mjs | Adds ESLint flat config for TS + tests. |
| Dockerfile | Adds multi-stage Docker build for production image. |
| CODE_OF_CONDUCT.md | Adds a project Code of Conduct document. |
| .gitignore | Updates ignore patterns (but missing .npm-cache/). |
| .github/PULL_REQUEST_TEMPLATE.md | Adds PR template (also highlights scope mismatch vs #477). |
| .github/CODEOWNERS | Adds CODEOWNERS rules for sensitive paths and repo. |
| .dockerignore | Adds a Docker build-context ignore list. |
| .kiro/specs/adaptive-polling-intervals/.config.kiro | Adds Kiro spec config metadata. |
| .npm-cache/** | Adds numerous npm cache artifacts (should not be committed). |
Review details
- Files reviewed: 31/1108 changed files
- Comments generated: 6
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| deb9453fb8ef48d7f0d55057848a492dbc76f713 {"key":"make-fetch-happen:request-cache:https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz","integrity":"sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==","time":1782803103686,"size":7896,"metadata":{"time":1782803103672,"url":"https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz","reqHeaders":{},"resHeaders":{"cache-control":"public, immutable, max-age=31557600","content-type":"application/octet-stream","date":"Tue, 30 Jun 2026 07:05:04 GMT","etag":"\"b421f08b7e823a774e19369d401078db\"","last-modified":"Wed, 08 Sep 2021 07:19:19 GMT","vary":"Accept-Encoding"},"options":{"compress":true}}} |
| registerGetContractStatusTool(server, getDb); | ||
| registerGetExtensionCostsTool(server); | ||
|
|
||
| server.tool( |
|
|
||
| export const GET_EXTENSION_COSTS_TOOL_NAME = "get_extension_costs"; | ||
|
|
||
| export function registerGetExtensionCostsTool(server: McpServer): void { |
| async ({ contractId, period }) => { | ||
| const db = getDatabase(); | ||
| const result = getExtensionCosts(db, contractId, { period }); | ||
|
|
| ## What does this PR do? | ||
|
|
||
| <!-- One or two sentences. Link the issue this addresses, if any: Closes #123 --> |
| export type AlertEventType = "budget_exhausted" | "system_error"; | ||
| export type AlertSeverity = "warning" | "error" | "info"; | ||
|
|
||
| export interface AlertEvent { | ||
| type: AlertEventType; | ||
| severity: AlertSeverity; | ||
| contractId: string; | ||
| message: string; | ||
| timestamp: number; | ||
| } | ||
|
|
||
| export interface NotificationChannel { | ||
| type: "slack" | "webhook" | "discord"; | ||
| send: (event: AlertEvent) => Promise<{ success: boolean }>; | ||
| } |
What does this PR do?
Closes #477
Why?
Does this touch secret-key handling or transaction submission?
Checklist
npm test)npx tsc --noEmit)npm run lint)console.login core logic